home *** CD-ROM | disk | FTP | other *** search
/ Aminet 45 / Aminet 45 (2001)(GTI - Schatztruhe)[!][Oct 2001].iso / Aminet / game / role / ldmud-3.2-bin.lha / mud / doc / efun / parse_command < prev    next >
Text File  |  2001-05-25  |  7KB  |  163 lines
  1. DEPRECATED
  2. SYNOPSIS
  3.         int parse_command (string cmd, object  env, string fmt, mixed &var, ...)
  4.         int parse_command (string cmd, object* arr, string fmt, mixed &var, ...)
  5.  
  6. DESCRIPTION
  7.         parse_command() is basically a spiffed up sscanf operating
  8.         on word basis and targeted at recognizing object descriptions from
  9.         command strings.
  10.  
  11.         The efun takes the command string <cmd> and the object(s) <env>/<arr>
  12.         and tries to match it against the format string <fmt>. Successfully
  13.         matched elements are assigned to the variables <var>.... The result
  14.         from the efun is 1 if the command could be fully matched, and 0
  15.         otherwise.
  16.  
  17.         If the objects are given as a single object <env>, the efun matches
  18.         against the given object and all objects contained therein. Otherwise,
  19.         if the objects are given as an array <arr> of objects, the efun
  20.         matches only against the given objects.
  21.  
  22.         Compat mode only: If <env> is 0, environment(this_player()) is used
  23.         as default.
  24.  
  25.         The format string <fmt> consists of words, syntactic markers, and
  26.         %-directives for the values to parse and return in the variables.
  27.         A typical example is " 'get' / 'take' %i " or
  28.         " 'spray' / 'paint' [paint] %i ". The elements in detail are:
  29.  
  30.            'word': obligatory text
  31.            [word]: optional text
  32.            /     : Alternative marker
  33.            %o    : Single item, object
  34.            %s    : Any text
  35.            %w    : Any word
  36.            %p    : One of a list of prepositions.
  37.                    If the variable associated with %p is used to pass
  38.                    a list of words to the efun, the matching will take
  39.                    only against this list.
  40.            %l    : non-compat: Living objects
  41.                    compat: a single living object
  42.            %i    : Any objects
  43.            %d    : Number >= 0, or when given textual: 0-99.
  44.  
  45.         A <word> in this context is any sequence of characters not containing
  46.         a space. 'living objects' are searched by calls to the (simul)efuns
  47.         find_player() and find_living(): both functions have to accept a name
  48.         as argument and return the object for this name, or 0 if there
  49.         is none.
  50.  
  51.         The results assigned to the variables by the %-directives are:
  52.  
  53.            %o : returns an object
  54.            %s : returns a string of words
  55.            %w : returns a string of one word
  56.            %p : if passed empty: a string
  57.                 if passed as array of words: var[0] is the matched word
  58.            %i : returns an array with the following content:
  59.                   [0]: int: the count/number recognized in the object spec
  60.                             > 0: a count (e.g. 'three', '4')
  61.                             < 0: an ordinal (e.g. 'second', 'third')
  62.                             = 0: 'all' or a generic plural such as 'apples'
  63.                   [1..]: object: all(!) objects matching the item description.
  64.                                  In the <env> form this may be the whole
  65.                                  recursive inventory of the <env> object.
  66.                 It is up to the caller to interpret the recognized numeral
  67.                 and to apply it on the list of matched objects.
  68.            %l : non-compat: as %i, except that only living objects are
  69.                             returned.
  70.                 compat: as %o, except that only a living object is returned.
  71.  
  72.         %i (and non-compat-%l) match descriptions like 'three red roses',
  73.         'all nasty bugs' or 'second blue sword'.
  74.  
  75.         Note: Patterns of type: "%s %w %i" might not work as one would expect.
  76.         %w will always succeed so the arg corresponding to %s will always be
  77.         empty.
  78.  
  79.  
  80.         The implementation of parse_command() differs between compat mode
  81.         and non-compat mode drivers mainly in how the efun retrieves the necessary
  82.         information from the mudlib objects.
  83.  
  84. DESCRIPTION -- non-compat mode
  85.  
  86.         To make the efun useful it must have a certain support from the
  87.         mudlib: it calls a set of functions in objects to get the
  88.         information it needs to parse a string.
  89.  
  90.           1. string *parse_command_id_list()
  91.               Normal singular names of the object.
  92.  
  93.           2. string *parse_command_plural_id_list() - optional
  94.               Plural forms of the names returned by 1.
  95.               If this function doesn't exist, the parser tries to pluralize
  96.               the names returned by 1.
  97.  
  98.           3. string *parse_command_adjectiv_id_list() -  optional
  99.               All adjectives associated with this object.
  100.  
  101.         All names and adjectives may consist of several words separated
  102.         by spaces.
  103.  
  104.         These functions should exist in all objects and are therefore best
  105.         put into a mandatory inherit file (e.g. /std/object.c).
  106.  
  107.         In addition the master object may offer the same functions to provide
  108.         reasonable defaults (like 'thing' as generic singular name):
  109.  
  110.              string *parse_command_id_list()
  111.                - Would normally return: ({ "one", "thing" })
  112.  
  113.              string *parse_command_plural_id_list()
  114.                - Would normally return: ({ "ones", "things", "them" })
  115.  
  116.              string *parse_command_adjectiv_id_list()
  117.                - Would normally return ({ "iffish" })
  118.  
  119.         Two additional functions in the master object provide the default
  120.         list of prepositions (needed for %p) and the single 'all' word:
  121.  
  122.              string *parse_command_prepos_list()
  123.                - Would normally return: ({ "in", "on", "under", "behind",
  124.                  "beside" })
  125.  
  126.              string parse_command_all_word()
  127.                - Would normally return: "all"
  128.  
  129.  
  130.         int parse_command(string, object|object*, string, destargs...)
  131.  
  132. DESCRIPTION -- compat mode
  133.  
  134.         To make the efun useful it must have a certain support from the
  135.         mudlib: it calls a set of functions in objects to get the
  136.         information it needs to parse a string.
  137.  
  138.           1. int id (string txt)
  139.               txt is an object name of the form "adj1 adj2 ... name".
  140.               The function has to return non-zero if txt is a valid
  141.               (singular) name for this particular object.
  142.  
  143.           2. int plural_id (string txt)
  144.               txt is an object name of the form "adj1 adj2 ... name".
  145.               The function has to return non-zero if txt is a valid
  146.               plural name for this particular object.
  147.  
  148.           3. string adjectiv_id()
  149.               When parsing commands like "get all red ones", the result
  150.               from this function is used to construct the text passed
  151.               to id(); in this example "red <adjectiv_id>". If this
  152.               function doesn't exist, the last word from the result
  153.               of short() is used instead.
  154.  
  155. EXAMPLE
  156.  
  157.         object *items;
  158.         parse_command( "take apple",environment(this_player())
  159.                      , " 'get' / 'take' %i ",items);
  160.  
  161. SEE ALSO
  162.         sscanf(E)
  163.